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INTRODUCTION 


SECTION  1 
INTRODUCTION 


The  ideal  way  to  debug  a computer  program  is  to  write  it  correctly  in  the  first  place 
and  not  debug  it  at  all.  Experience  has  shown,  however,  that  most  programs  of 
moderate  size  contain  errors,  and  that  debugging  is  a significant  part  of  software 
production  BAIL  is  a tool  which  is  designed  to  be  useful  for  interactive  debugging 
of  programs  written  in  SAIL  [4],  a high-level  ALGOL-based  language  for  Digital 
Equipment  Corporation  (DEC)  PDP-10  computers. 

In  the  very  early  days  of  computing,  debugging  was  done  at  the  console  of  the 
computer  The  programmer  manipulated  switches,  observed  lights,  and  had  complete 
control  of  the  whole  machine.  The  programmer  could  examine  and  change  any  location 
in  memory  and  could  start,  stop,  and  single-step  the  processor.  Console  debugging 
soon  became  uneconomical  on  medium  aid  large-scale  machines.  It  is  still  used  on 
minicomputers.  This  type  of  debugging  i s at  the  machine-language  level;  the  lights  and 
switches  are  direct  representations  of  bits-  inside  the  machine. 

Debugging  moved  to  the  assembly  language  level  with  the  development  of  interactive 
time-sharing  systems  in  the  early  1960’s.  The  programmer  typed  commands  at  a 
terminal,  and  a collection  of  special  subroutines  interpreted  the  commands  so  that  the 
effect  was  similar  to  working  at  the  console  of  the  machine.  Instead  of  communicating 
in  bits  the  programmer  and  subroutines  used  character  strings  in  the  format  of  octal 
and  decimal  integers,  text,  symbolic  machine  instructions,  and  symbolic  addresses. 
One  of  the  most  important  features  of  the  debugging  routines  was  the  ability  to 
Stipend  the  execution  of  the  program  bein|  debugged,  enter  the  debugging 
routines,  communicate  with  the  programmer,  resume  execution,  and  make  the  whole 
process  invisible  to  the  program  being  debugged.  This  process  became  known  as 
breakpointing;  the  location  where  the  mam  program  was  stopped  is  a breakpoint,  and 
the  debugging  routines  are  called  a brsckpcini  package.  The  premier  example  of  a 
symbolic  debugging  package  is  DDT  [1],  developed  for  use  on  the  DEC  PDP-1  and 
isyuuently  extended  for  use  on  the  PDP-6  and  PDP-10.  DDT  and  its  derivatives 
are  still  among  the  most  powerful  tools  for  debugging  assembly  language  programs. 

BAIL  is  a high-level  breakpoint  package  for  use  with  SAIL  programs.  (Swinehart  [3]  and 
Satterthwaite  [2]  contain  descriptions  of  other  high-level  debugging  systems.) 
Communication  between  the  programmer  and  BAIL  is  in  character  strings  which  are  the 
names  and  values  of  SAIL  objects.  BAIL  reads  genera’  SAIL  expressions  typed  by 
the  programmer,  evaluates  them  in  the  context  of  the  place  in  the  program  where 
execution  was  suspended,  and  prints  the  resulting  value  in  an  appropriate  format.  The 
evaluation  and  printing  are  performed  just  as  if  the  programmer  had  inserted  an 
extra  statement  into  the  wifmai  prtgrwr  st  the  poH  where  execution  swes 
suspended.  BAIL  also  provides  a way  to  talk  about  the  program,  to  answer  the 
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questions  "Where  was  execution  suspended?",  "By  what  chain  of  procedure  calls 
did  execution  proceed  to  that  point?",  and  "What  is  the  text  of  the  program?" 

In  order  to  perform  these  functions,  BAIL  must  havp  some  information  about  the 
program  being  debugged.  The  SAIL  compiler  will  produce  this  information  if  the 
program  is  compiled  with  an  appropriate  value  supplied  for  the  /B  switch.  (See  the 
technical  portion  of  the  manual  for  the  exact  meaning  of  the  various  switch  values.) 
In  these  examples  the  compiler  produces  two  files.  File  PROG.REL  contains  the 
relocatable  code  and  loader  r.ctrjctkra,  arJ  ttL#  TOW.l  cental--*  th®  Worrr.otAon  for 
BAIL.  The  PR0G.SM1  information  consists  of  the  name,  type,  and  accessing 
information  for  each  variable  and  procedure,  the  location  of  the  beginning  and  end 
of  each  statement,  and  a description  of  the  block  structure. 

The  code  for  BAIL  itself  is  loaded  automatically  when  the  program  is  loaded.  In  order 
for  the  added  Information  and  code  to  be  of  any  use,  it  must  be  possible  to  give 
control  to  BAIL  at  the  appropriate  time.  An  explicit  call  to  BAIL  is  possible  by 
declaring  EXTERNAL  PROCEDURE  BAIL;  in  the  program  and  using  the  procedure  call 
gtJL-.  Thin  werks  wefl  if  tt  ca-  be  predicted  in  advance  where  BAILin*  might  be  helpful. 
Runtime  errors,  such  as  subscript  overflow  or  CASE  index  errors,  are  not  as  predictable; 
but  responding  "B"  to  the  SAIL  error  handler  will  activate  BAIL.  Interrupting  the 
program  while  it  is  running  (to  investigate  a possible  infinite  loop,  for  example)  can  De 
achieved  under  the  TENEX  operating  system  by  typing  control-B.  On  a DEC  TOPS- 10 
operating  system,  first  return  to  monitor  mode  by  typing  one  or  more  control-C's,  then 
activate  BAIL  by  typing  DD<cr>. 

BAIL  performs  some  initialization  the  first  time  it  is  entered  The  information  in  the 
.SMI  file(s)  is  collected  and  processed  into  a file  PROG.BAI.  This  new  file  reflects  all 
d Ihe  information  from  the  5V 1 files  of  any  separately-compiled  programs,  and 
the  relocation  performed  by  the  loader.  If  the  core  image  was  SAVEd  or  SSAVEd  then 
in  subsequent  runs  BAIL  will  use  the  .BAI  file  and  bypass  much  of  the  initialization. 

BAIL  prompts  the  programmer  for  input  by  typing  a number  and  a colon.  The  number 
indicates  how  many  times  BAIL  has  been  entered  but  not  yet  exited,  and  thus  is  the 
recursion  depth  inside  BAIL  Input  to  BAIL  can  be  edited  using  the  standard  SAIL 
input-editing  characters  for  the  particular  operating  system  under  which  the  program 
is  running.  [BAIL  requests  input  via  INCHWL  on  DEC  TOPS- 10  systems  and  via  INTTY  on 
TENEX  systems.]  Input  is  terminated  whenever  the  editor  activates,  string  quotation 
marks  balance,  and  the  last  character  is  a semicolon;  otherwise  input  lines  are 
concatenates  Ho  one  siring  before  being  processed  further. 

The  programmer  may  ask  BAIL  to  evaluate  any  SAIL  expression  or  procedure  call 
whose  evaluation  would  be  legal  at  the  point  at  which  execution  of  the  program  beirg 
debugged  was  suspended  (except  that  expressions  involving  AND,  OR,  IF-THEN- 
ELSE,  and  CASE  are  not  allowed.)  BAIL  evaluates  the  expression,  prints  the 
resulting  value  in  an  appropriate  format,  and  requests  turtner  input. 

Declared  inside  BAIL  are  several  procedures  whose  values  or  side  effects  are  useful 
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in  the  debugging  process,  These  procedures  handle  the  insertion  and  deletion  of 
breakpoints,  display  t^e  static  and  dynamic  scope  of  the  current  breakpoint,  display 
selected  statements  from  the  source  program,  allow  escape  to  an  assembly- 
language  debugging  program,  and  cause  resumption  of  the  suspended  main 
program.  These  procedures  ai e described  in  the  technical  portion  of  i he  manual, 


The  following  examples  illustrate  many  of  the  features  available  in  BAIL.  Text  was 
recorded  from  an  actual  session  on  the  computer. 
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SECTION  2 
EXAMPLES 


@TYPE  TESTES Al 

; <RE ISER>TEST1  .SAI ; 1 SAT  10-NAY-75  2:37Pt1 


This  is  a test  program,  run  on  TENEX. 

PAGE  1 


BEGIN  "TEST" 

EXTERNAL  PROCEDURE  BAIL; 


INTEGER  I , J , K ; 

STRING  A , B , C ; 

REAL  X , Y , Z ; 

INTEGER  ARRAY  FOD  [0:151;  STRING  ARRAY  STRARR  tl ; 5, 2:G]  ; 
INTEGER  ITEHVAR  DAY;  I TENVAR  QQ; 


INTEGER  PROCEDURE  A00( INTEGER  I,J);  BEGIN  "ADD" 
OUTSTR  (" 

HI,  GLAD  YDU  STOPPED  BY,");  RETURN ( I+J)  END  "A00"; 


RECURSIVE  INTEGER  PROCEDURE  FACT (INTEGER  N) ; BEGIN  "FACT" 
RETURN  (IF  N LEQ  1 THEN  1 ELSE  N*FACT (N-l) ) END  "FACT"; 


SIHPLE  PROCEDURE  S I HPROC (REFERENCE  INTEGER  M) * BEGIN  "SBEG" 
ADD  ( M , ti*-32 ) END  "SBEG"; 


FOR  1-0  STEP  1 UNTIL  15  00  F00[1]-I*I; 

FOR  1-1  STEP  1 UNTIL  5 DO 

FDR  J-2  STEP  1 UNTIL  G 00 
STRARR  [ I , JI -64+8*1 +J; 

1-4;  J-6;  K-112; 

A-"BIG  OEAL";  B-"QEO";  C-"THE  LAST  PICASSO"; 


X-3. 141592G5;  Y-0;  Z-23.; 
BAIL; 


AOO  (7 , 45) ; 
SinPRDC(J) ; 


USERERR (0, 1 , "THIS  IS  A TEST"); 


ENO  "TEST"; 
TL 


. -.Mvc, i-fWf 
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Compile  and  load  with  BAIL. 

@SAID- SAV ; 10  _ (?  rnp  HELP) 

TENEX  SAIL  8.1  4-4-75  t?  PUH  Hturi 

*n:sn,<- 

%*./27  II 

TEST 1 . SA 1 ; 1 1 
END  OF  COMPILATION. 

LOADING 


LOADER  G+3K  CORE 
EXECUTION 


tc 


Save  the  core  image  for  later  use. 
,ssm:  (PAGES  FROM)  0 (TOI  S77  (ONI  TEST , (NEW  FILE) 

[CONFIRM] 


&START 


Start  the  program. 

BAIL  identifies  itself  and  the  files  involved. 


BAIL  VER.  10-MAY-75 
TEST1 . SMI ; 2 
TEST1.SA1 ; 1 

End  of  BAIL  initial ization. 


1 : 45; 


The  "1;"  is  BAIL’S  prompt.  It  indicates  the  level  of 
recursive  Invocations  of  BAIL  and  the  fact  that  BAIL 
is  awaiting  input, 


See  how  constants  are  entered  and  printed.  The 
”45;<cr>"  is  typed  by  the  user,  and  the  next  lin 

"45"  is  BAIL’S  reply. 


45 

1 : 7.089; 

7.083000 

1 : "SOME  RANDOM  STRING  ; 
"SOME  RANDOM  STRING 


An  octal  constant}  all  printout  is  decimal. 


1 : ’275; 
183 


Symbolic  constants  More  than  one  expression 
requested 


1 ; TRUE,F  ALSE,NULL; 
-1  0 "" 


mJ & metf*.-.-™  . .. ... .4..A 
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Variables,  assignment 


3.141593 


Relational  operators;  remember  0 is  FALSE, 


1:98  LAND  * 17 


An  undeclared  identifier 


Usable  as  a desk  calculator 


9.141593 


Procedure  call 


1 : ADD(3,4); 

HI . GLAD  YOU  STOPPED  EY.  7 


Argument  list  checking 


1 : ADD(3); 

ADD  TAKES  2 ARGUMENTS.:  ADD (3) 


Arrays.  Array  name  only  gives  dimension  and 
subscript  bounds  information. 


1 : FOO; 

<ARRAY>  [ 0:151 
1 : FOO/4J; 


Substring  notation  has  been  extended  to  cover  array 
elements. 


1 : FOO (5  FOR  3j; 

25  36  49 

1 : STRARR; 


BAIL  — A debugger  for  SAIL 


EXAMPLES 


<ARRAY>[  1:5  2:6] 

'■■S™m/Jn?wv  -r  -u-  "V 


Array  accesses  are  interpreted 


1 : FOOf35]; 

SUBSCRIPTING  ERROR.  INDEX  VALUE  NIN  NAX 


Is/]; 

"BIG  DEAL" 
i ; lengtiua); 

8 

1:/; 

46 

ULOCATION(I); 

718 

UM  EMORY  pl8]<-64; 

64 
1:  /; 

64 


1 : A[2  TO  INF]; 

"IG  DEAL" 

1 : Ilf  3 TO  i]; 
"D" 


Is  /I 


"QEO" 


1 : TRACEC'F  ACT"); 
1 : F ACT  U); 


ENTERING  FACT  4 

entering  FACT  3 
entering  FACT  2 
entering  fact  1 

exiting  fact-  1 


EXITING  FACT-  2 
EXITING  FACT-  6 
24 


EXITING  FACT: 

1 : UNTRACEC'F  ACT'); 


35  0 IS  : FDD  135] 

LENGTH,  LOCATION,  and  MEMORY 


Substringing 


Type-in  must  be  terminated  by  a semicolon 


Tracing  of  procedure  entry  and  exit 


s 


-A..  ■»  3SME,  A.A.,  


. .... i ■ "•»■  '«  “•' 


I 

I 


I 
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U FACT (5); 
120 


1 : IiREAKC'ADD"); 
U/1D0(3,4); 


2:  ARCS; 
3 4 


2:  /; 

3 

2 :J; 

4 

2:  K; 
112 


2 : //CO; 

HI.  GLAD  YDU  STOPPED  BY. 


1 : !!CO; 

1 : TEXT; 


LEXICAL  SCDPE,  TOP  DDUN: 

8RUN8 

TEST 

ADD 


EXAMPLES 


Breakpointing 


Now  one  level  deeper  in  BAIL  recursion.  ARGS 
prints  the  arguments  list. 


Parameter  names  evaluate  just  like  variables. 


To  exit  from  one  level  of  BAIL 


The  message  is  from  ADD  itself;  the  value  7 is  from 
BAIL. 


Leave  another  level  of  BAIL. 

And  come  back  again.  Where  are  we? 
Static  block  structure 


DYNAMIC  SCOPE,  MDST  RECENT  FIRST: 
ROUTINE  TEXT 


Dynamic  procedure  invocations.  The  #4  means 
coordinate  number  4. 


ADD  #4 

TEST  #24 

SIMPROC (J) ; 


INTEGER  PROCEDURE  ADDUNTEGER  I , J) s BEGI 
ADO (7, 45): 


USERERR (0,1," 
1 : ARGS; 


.1... 
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1 : UNBRE/IKC'/IDD"); 


Remove  the  breakpoint. 


1 : !!G0; 

Output  from  other  calls  in  the  program 

HI.  GLAD  YDU  STDPPED  BY. 

HI.  GLAD  YDU  STDPPED  BY. 

CALLEDSFRDnEG42124  LAST  SAIL  CALL  AT  400303 
tB 


Entry  to  BAIL  from  the  error  handler 


1 : TEXT; 

LEXICAL  SCDPE,  TDP  DDUN: 

SRUNS 

DYNAMIC  SCDPE,  MDST  RECENT  FIRST: 

RSIMPLE.  *642124  %%%  FILE  NOT  V1EUABLE 

TEST  #2G  USERERR (0,1, "THIS  IS  A TEST"); 

END  "T 


UNKNDUN  ID: 


USETLEX(l); 

LEXICAL  SCOPE,  TDP  DOUN: 

SRUNS 

TEST 

Is/; 

G4 

1:C; 

"THE  LAST  PICASSO" 

1 : UGO; 

END  DF  SAIL  EXECUTION. 


The  static  scope  needs  to  be  set  back  one  on  the 
dynamic  chain. 
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. TYPE  TEST2.SAI 


BEGIN  “TEST" 

EXTERNAL  PROCEDURE  BAIL; 

REQUIRE  500  SYSTEM! POL,  10  PNAMES; 

LIST  L;  SET  S, SI , S2, S3, S4, S5 ; 

INTEGER  ITEM^SUNDAY;  ITEM  MONDAY,  TUESDAY,  WEDNESDAY,  THURSDAY,  FR I DAY, 

INTEGER  ITEMVAR  DAY;  ITEMVAR  QQ; 

ITEMVAR  ARRAY  PCI: 10]; 

RECORD 'CLASS  CELL  (RECDRD ' PD  INTER (CELL)  CAR.CDR); 

RECDRD ! PD  I NTER (CELL ) CX.CY; 


CX-NEW ! RECDRD  (CELL  1 ; 

C Y-NEW ! RECDRD (CELL); 

CELL : CAR  tCX)  -NULL  ! RECDRD ; CELL : CDR  (CX)  -NULL  IRECDRD; 
CELL ; CAR  ICY] -CX ; CELL:CDR (CY3 -NULL  I RECDRD; 


P Cl ] -SUNDAY;  P 12] -MDNDAY; 

L-  ( (SUNDAY)  I ; DATUM (SUNDAY) -0;  DAY-SUNDAY;  QQ-MONDAY;  S- (QQ) • 

51-  (SUNDAY, MDNDAY,  TUESDAY,  WEDNESDAY,  THURSDAY, FRIDAY, SATURDAY)  • 

52-  (MDNDAY , TUESDAY , WEDNESDAY , THURSDAY, FR  I DAY)  ; 

53-  (MONDAY,  WEDNESDAY, FRIDAY)  ; S4- (SATURDAY, SUNDAY)  ; 

S5-  (SUNDAY,  FRIDAY); 


FDREACH  DAY  SUCH  THAT  DAY  IN  SI  DD  MAKE  DAY  XDR  SUNDAY  EQV  SATURDAY; 


BAIL; 


USERERR (0,1, "THIS  IS  A TEST"); 
END  "TEST"; 


EXIT 

TC 

. EXECUTE  TEST2.SAK27B,) 
SAIL:  TEST2  1 
LDADING 

LDADER  15K  CORE 

25K  MAX  153  WORDS  FREE 

EXECUTION 

BAIL  VER.  10-MAY-75 
TEST2.SM1 
TEST2.SAI 

END  DF  BAIL  INITIALIZATION. 


1 : L; 

f (SUNDAY) ) 


EXAMPLES 


iyiu.i , a u.bt.  **«•. 
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1 : S-#,- 

(SUNDAY,  SATURDAY) 

1 : S5; 

(SUNDAY,  FRIDAY) 

1 : S*  UNION  S5; 

(SUNDAY,  FRIDAY,  SATURDAY) 

1 : FRIDAY  IN  S4; 

0 

1 : S2  LEQ  S2; 

-1 

1 : DAY; 

SATURDAY 
1 : DATUM(DAY); 

0 

1 : CX; 

CELL. 9231 
1 : CELLCARfCX/i 
NULL (RECORD 
1 : CEI.L.CARfCY  ]; 

CELL. 9231 

1 : SUNDAY  ASSOC  SATURDAY; 

(SUNDAY) 

1 : SUNDAY  EQV  SATURDAY; 

(SUNDAY,  MONDAY , TUESDAY,  WEDNESDAY,  THURSDAY,  FRIDAY,  SATURDAY) 
1 : SUNDAY  XOR  SATURDAY; 

PHI 

1 : SUNDAY  EQV  SUNDAY; 

PHI 
1 : TC 
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aTESTLSAV;! 


Go  back  to  the  earlier  example 


Initialization  uses  file  created  last  time. 

BAIL  ver.  10~f1ay-75  using  TEST1.BAI 
End  of  BAIL  initial  ization. 


Switch  /27B  at  compile-time  makes 
predeclared  runtime  routines  known  to  BAIL. 

1 : OPENF  ILE(NULL"W"); 

TODAY.TMP 

1:  OUT(4,"TII IS  IS  A TEMPORARY  FILE  CREATED  WHILE  IN  BAIL."); 


1 : CFILE(i); 

-1 

1 : OPENF ILEC\"RC"); 

TODAY.TMP  COLD  VERSION] 

4 

1 ‘ S''TH I sTs'T ’TEMPORARY  FILE  CREATED  UHILE  IN  BAIL." 
1 ’ ^ 'Saturday, ^ may  10,  197s  17s 19: 29" 


Quickie  review  of  BAIL  capabilities 


Is? 


EXPRESSION; 

PROCEDURE 'CALL; 

TRACE  ("PROCEDURE"); 

UNTRACE  ("PROCEDURE"); 

BREAK  ("PROCEDURE.  BLOCK,  OR  LABEL  ; 
UNBREAK  ("PROCEDURE,  BLOCK,  OR  LABEL'); 
! ! GO; 

SETLEX  (LEVEL); 

TEXT; 

ARGS; 

HELP; 

DOT; 


IsTC 


End  of  the  examples. 
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SECTION  3 

COMPILE-TIME  ACTION 


The  principal  result  of  activating  BAIL  at  compile-time  is  the  generation  of  a file  of 
information  about  the  source  program  for  use  by  the  run-time  interpreter.  This  file  has 
the  same  name  as  the  .REL  file  produced  by  the  compilation,  except  that  ths  extension  is 
.SMI.  If  requested,  BAIL  will  also  generate  some  additional  code  for  SIM°LE  procedures 
to  make  them  more  palatable  to  the  run-time  interpreter. 


Tne  action  of  BAIL  at  compile  time  is  governed  by  the  value  of  the  / B switch  passed  to 
the  compiler.  If  the  value  of  this  switcn  is  zero  (the  default  h no  value  is  specified)  then 
BAIL  is  completely  inactive.  Otherwise,  the  low-order  bits  determine  the  actions  which 
BAIL  performs.  [The  value  of  the  /B  switch  is  interpreted  as  octal.] 


bit  action 


If  this  bit  is  on,  then  the  .SMI  file  will  contain  the  program  counter  to  source/listing 
text  directory. 


If  this  bit  is  cn,  then  the  .SMI  file  will  contain  symbol  information  for  all  SAIL 
symbols  encountered  in  the  source.  If  this  bit  is  off,  then  information  is  kept  only 
for  pTocedufes,  parameters,  blocks,  and  internals;  he.,  rcr.-  Internal  local  variables 
are  not  recorded. 


If  this  bit  is  on,  then  SIMPLE  procedures  will  get  procedure  descriptors,  and  one 
additional  instruction  (a  JFCL  0,  which  is  the  fastest  machine  no-op  Instruction)  is 
inserted  at  the  beginning  of  SIMPLE  procedures.  Except  for  these  two  changes,  all 
properties  of  SiMPLE  procedures  remain  the  same  as  before.  The  procedure 
descriptor  is  necessary  if  the  procedure  is  to  be  called  interpretively  or  if  the 
procedure  is  to  be  TRACEd, 


’10  If  this  bit  is  on,  then  BAIL  will  not  be  automatically  loaded  and  initialized,  although 
all  other  actions  requested  are  performed,  This  is  primarily  intended  to  make  it 
easier  to  debug  new  versions  of  BAIL  without  interfering  with  SYS;BAIL.REL.  By 
using  this  switch  the  decision  to  load  BAIL  is  delayed  until  load  time. 


’20 


If  this  bit  is  on,  then  a request  to  load  SYS:BAIPDn.REL  is  generated.  This  file 
contains  procedure  descriptors  for  most  of  the  SAIL  predeclared  runtime  routines, 
making  it  possible  to  call  them  from  BAIL,  The  procedure  descriptors  and  their 
symbols  occupy  about  6K, 


The  B switch  must  occur  on  the  binary  term,  not  the  listing  or  source  term.  Thus: 
.R  SAIL  or  .COM  PROG(27B,) 

*PROG/27B«-PROG 
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The  program  counter  ££ 

coordinate  counter  is  zeroed  a the  Beginning  or m K , least  one  word 

°?6  ,0^  et.Ch  Bhi^n’  compiled  sincTthe  previous1  coordinate  was  defined.  Note  that 

rrMMENT^  are  seen  onftby  he  scanne?,  not  the  parser,  and  that  OEFINEs  and  many 
COMMENTS  are  seen  y y d0  not  cause  instructions  to  be  generated.  For 

declarations  merely  detine  y coordinate  number,  the  value  of  the  program 

each  coordinate  the  dmectory  contains  the^co  ^ ^ appropria(e  p|ace  |s  the  source 

r^1  hstingPfile  is  being  produced^, «»  tgj*  -e  jtis 

switch  is  on. 


The  symbol  table  information  consists  of  the  block  structure  and  the  name,  access 
information,  and  type  for  each  symbol. 


if  a rfgIN-END  oair  has  declarations  <i.e„  is  a true  block  and  not  just  a com, pound 
sta  emenO  but  does  not  have  a name,  then  BAIL  will  invent  one  The  name  is  of  the 
form  Bnnnn  where  nnnn  is  the  decimal  value  of  the  current  coordinate. 
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SECTION  4 


RUN-TIME  ACTION 


The  BAIL  run-time  interpreter  is  itself  a SAIL  program  which  resides  on  the  system  disk 
area.  This  program  is  usually  loaded  automatically,  and  does  some  initialization  when 
entered  for  the  first  time.  The  initialization  generates  a ,BAI  file  of  information  collected 
from  the  .SMI  files  produced  by  separate  compilations  (if  any).  The  .SMI  files 
correspond  to  .REL  files,  and  the  .BAI  file  corresponds  to  the  ,DMP  or  .SAV  file.  Like 
RPG  or  CCL,  BAIL  will  try  to  bypass  much  of  the  initialization  and  use  an  existing  .BAI  file 
if  appropriate.  During  initializat'on  BAIL  displays  the  names  of  the  .SMI  files  it  is 
processing.  For  each  .SMI  file  which  contains  program  counter/text  index  information, 
BAIL  displays  the  names  of  the  text  files  and  determines  whether  the  text  files  are 
accessible. 


The  interpreter  is  activated  by  explicit  call,  previously  inserted  breakpoints,  or  the  SAIL 
error  handler.  For  an  explicit  call,  say  EXTERNAL  PROCEDURE  BAIL;  ...  BAIL;.  From  the 
error  handler,  respond  B.  Breakpoints  will  be  described  later  in  this  section. 


4.1  - Debugging  Requests 


When  entered,  BAIL  prints  the  debugging  recursion  level  followed  by  a colon,  and  awaits 
a debugging  request.  BAIL  accepts  ALGOL  and  LEAP  expressions  of  the  SAIL  language. 
A complete  description  is  given  in  [4]  and  in  the  addenda  describing  the  syntax  of 
records  and  record-pointers,  The  following  exceptions  should  be  noted.  Expressions 
involving  control  structure  are  not  allowed,  hence  BAIL  will  not  recognize  AND,  OR,  1F- 
THEN-ELSE,  or  CASE.  Bracketed  triple  items  are  not  allowed.  The  TO  and  FOR 
substring  and  sublist  operators  have  been  extended  to  operate  as  array  subscript 
ranges,  FOR  PRINT-OUT  ONLY.  If  F00  is  an  array,  then  F00[3  TO  7];  will  act  like  FOO[3], 
r00[4],  FOGtSJ,  r^[7j;  tut  is  taster  L type.  This  extension  is  tor  print  -uut 

only;  no  general  APL  syntax  oi  semantics  are  provided. 


BAIL  evaluates  symbolic  names  according  to  the  scope  rules  of  ALGOL,  extended  tc 
always  recognize  names  which  are  globally  unique  and  have  a fixed  memory  location 
thing  except  ; recursive  locnls).  For  *ry  nctivatic  - ci  3 AIL, 
initial  scope  is  the  ALGOL  scope  of  the  statement  from  which  BAIL  was  activated.  The 
procedure  SETLEX  (see  below)  may  be  used  to  change  the  scope  to  that  of  any  one  of 
the  links  in  the  dynamic  activation  chain. 


Several  procedures  are  predeclared  in  the  outermost  block  to  handle  breakpoints  and 
display  information.  These  are  described  individually  below. 

15 


mm 


Has 


BAIL  --  A debugger  for  SAIL 


RUN-TIME  ACTION 


4.16  - ARGS 

STRING  PROCEDURE  ARGS; 

The  arguments  to  the  procedure  which  was  most  recently  called. 


4.3  - BREAK 


PROCEDURE  BREAK("location","condition"(NULL),"action"(NULL),count(0)); 


BREAK  inserts  a breakpoint.  The  syntax  for  the  first  argument  is 
< I oc at i o n > ::==< I abel > |< pr ocedure> |< bl ock  name>[#<nnnn> 
j<block  name><delim><location> 
<delim>::=<any  character  not  legal  in  an  identified 
<nnnn>::=<decimal  coordinate  numbed 


If  the  location  is  specified  by  the  <block  name><delim><location>  construe  then  he 
blocks  of  the  core  image  are  searched  in  ascending  order  of  address  of  BEGINS  until  the 
first  <block  name>  is  matched.  The  search  continues  until  the  second  <block  name>  is 
matched  etc  The  breakpoint  is  inserted  at  the  label,  procedure,  or  coordinate  declared 
within  the  scope  of  the  last  <block  name>.  Tnis  detailed  specification  is  not  usually 
necessary,  as  shown  in  the  examples.  The  last  three  parameters  are  default  able  and 
need  not  be  specified,  again  as  in  the  examples.  The  action  taken  at  a breakpoint  is 


IF  LENGTH(condition)  AND  EVAL(condition)  AND  (count<-count-l)<0  AND 
LENGTH(action)  THEN  EVAL(action); 

EVAL(TTY); 


Here  EVAL  is  a procedure  which  evaluates  its  string  argument  and  returns  the  value  of 
the  last  expression  evaluated  (similar  to  PROGN  in  LISP). 


4.4  - DDT 
PROCEDURE  DDT; 


This  procedure  transfers  control  to  an  assembly  language  debugging  program  (if  one  was 
loaded). 
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4.5  - HELP 


PROCEDURE  HELP; 


A list  of  options,  including  short  descriptions  of  the  procedures  described  in  this  section, 
is  orinted.  A question  mark  followed  by  a carriage  return  is  interpreted  as  a call  to 
HELP 


4.6  - SETLEX 


PROCEDURE  SETLEX(level); 


Evaluating  SETLEX(n)  changes  the  static  (lexical)  scope  to  the  scope  of  the  n-th  entry  in 
the  dynamic  scope  list.  SETLEX(O)  is  the  scope  of  the  breakpoint;  SETLEX(l)  is  the 
scope  of  the  most  recent  procedure  call  in  the  dynamic  scope,  etc. 


4.7  - SHOW 


STRING  PROCEDURE  SHOWffirst,  last(O)); 


The  text  of  the  program  from  the  source  or  listing  file.  If  last  is  less  than  first  then  set 
last  to  last+first.  Return  coordinates  first  through  last.  5H0W(5,3)  gives  coordinates  5, 
6,  7,  and  8;  SHOW(5,7)  gives  coordinates  5,  6,  and  7;  SH0W(5)  gives  coordinate  5 only. 


A plu<-  sign  ("+")  following  the  coordinate  number  indicates  that  the  values  of  some 
variables  have  been  carried  over  in  accumulators  frnm  the  previous  coordinate. 
Changing  the  value  of  variables  might  not  be  successful  in  such  a case,  because  BAIL  will 
not  change  any  accumulator  value  directly.  The  MEMORY  construct  can  be  used  to 
fT’Odity  ary  iccatiin  in  a core  image,  including  the  -jccumulntors. 


4.8  - TEXT 


STRING  PROCEDURE  TEXT; 


The  current  static  and  dynamic  scopes,  with  text  from  the  source  or  listing  file. 
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RUN-TIME  ACTION 


4.9  - TRACE 


PROCEDURE  TRACEfprocedure"); 


Special  breakpoints  are  inserted  at  the  beginning  and  end  of  the  procedure  named.  On 
entry,  the  procedure  name  and  arguments  are  typed.  On  exit,  the  name  and  value 
returned  (if  any)  are  typed. 


4.10  - TRAPS 

STRING  PROCEDURE  TRAPS; 

A list  of  the  current  breakpoints  and  traces. 


4.11  - UNBREAK 

PROCEDURE  UNBREAK("location”); 

The  breakpoint  at  the  location  specified  is  removed. 


4.12  - UNTRACE 

PROCEDURE  UNTRACECprocedure"); 

The  breakpoints  inserted  by  TRACE  are  removed. 


4.13  - GO 


pseudoPROCEDURE  !!G0; 


An  immediate  exit  from  the  current  instantiation  of  BAIL  is  taken  and  execution  of  the 
program  is  resumed.  !!G0  is  a reserved  word  (the  only  one)  in  BAIL. 
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RUN-TIME  ACTION 


4.14-  GSTEP 


pseudoPROCEDURE  IIGSTEP; 


Temporary  breakpoints  are  inserted  at  ell  of  the  logical  exits  of  the  current  statement, 
and' execution  of  the  program  is  resumed.  Logical  exits  are  the  next  statement  and 
locations  to  which  the  current  statement  can  jump,  excluding  any  procedure  calls.  All  of 
the  breakpoints  which  are  inserted  will  be  removed  as  soon  as  one  of  them 
encountered. 


IS 


4.15 -STEP 

pseudoPROCEDURE  !!STEP; 


Temporary  breakpoints  are  inserted  at  all  locations  to  which  the  current  statement  can 
jump,  including  procedure  calls,  and  execution  of  the  program  is  resumed. 


4.16  - STRING  TYPEOUT 


Strings  are  usually  typed  so  that  the  output  looks  the  same  as  the  input,  i.e.,  a string  is 
typed  with  surrounding  quotation  marks  and  doubled  internal  quotation  marks.  For 
SHOW,  ARGS,  and  TEXT  this  would  ordinarily  create  confusion,  so  they  are  handled 
specially.  When  these  procedures  are  evaluated  they  set  a flag  which  inhibits  quotation 
mark  fiddling,  provided  that  no  further  evaluation  takes  place  before  me  next  typeout. 
Thus  SH0W(5,3);  will  be  typed  plain,  but  STR<-SH0W(5,3);  will  have  quotation  marks 
massaged. 


4.17  - BAIL  and  DDT 


If  BAIL  is  initialized  in  a core  image  which  does  not  have  DDT  or  RAID,  then  things  will  be 
set  up  so  that  the  monitor  command  DDT  gets  you  into  BAIL  in  the  right  way.  That  is, 
BAIL  will  be  your  DDT.  To  enter  BAIL  from  DDT  (provided  that  the  SAIL  initialization 
sequence  has  already  been  performed),  use 
pushi  P,<program  counter>8X 
JRST  BAILSX 

For  example,  if  .JBOPC  contains  the  program  counter, 

PUSH  Pj.JBOPCSX 
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JRST  BAILSX 


The  entry  B.  provides  a path  from  DDT  to  BAIL  which  works  whether  or  not  the  core 
image  has  been  initialized.  One  use  of  this  feature  is  to  BREAK  a procedure  in  an 
existing  production  program  without  recompiling,  For  example, 

prog  originally  compiled,  loaded  with  BAIL  and  DDT,  and  SAVEd 

taGET  PROG 
@DD 
B.SG 

BAIL  initialization 


liBREAKCprocedure"); 
1 :!!G0; 


SG 


To  enter  DDT  from  BAIL,  simply  say  DDT;.  For  operation  under  TENEX,  control-B  is  a 
pseudo-interrupt  character  which  gets  you  into  BAIL 


4.18- WARNINGS 


Since  BAIL  is  itself  a SAIL  procedure,  entering  BAIL  from  the  error  handler  or  DDT  after 
a push-down  overflow  or  a string  garbage  collection  error  will  get  you  into  trouble. 


SIMPLE  procedures  cause  headaches  for  BAIL  because  they  do  not  keep  a display 
pointer.  [Indeed,  the  compiler  gets  lost  in  the  following  example,  and  does  not  complain: 
BEGIN  "LOST" 

PROCEDURE  A( INTEGER  I);  BEGIN  "A" 

SIMPLE  PROCEDURE  B;  OUTSTRf'THE  VALUE  OF  I IS  & CVS(I)); 

PROCEDURE  C( INTEGER  J);  B; 

C(  2); 

END  "A"; 


A(  1); 

END  "LOST"; 


] 


BAIL  tries  valiantly  to  do  the  right  thing,  but  occasionally  it  also  gets  lost.  BAIL  will  try 
to  warn  you  if  it  can.  In  general,  looking  at  value  string  parameters  of  SIMPLE 
procedures  does  not  work. 
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SECTION  5 

RESOURCES  USED 


I.  Compile-time 


A.  One  channel.  This  means  that  REQUIREd  sourcn  tiles  may  only  be  nested  to  a 
depth  of  about  9. 


B.  Memory.  Up  to  ll*(maximum  lexical  nesting  depth)  more  words  of  memory  may 
lie  required  compared  with  previous  compilations. 


C.  CPU  time.  Approximately  0.3  seconds  per  page  of  dense  text. 
I.  Run-time 


A.  Channels.  Three  during  initialization,  two  thereafter.  Channels  are  obtained  via 
GETCHAN. 


B.  BAIL  uses  7 of  the  privileged  breaktables,  obtaining  them  via  GETBREAK. 


C.  REQUIRE  64  STRINGIPDL.  Necessary  if  the  debugging  recursion  level  will  exceed 
3 or  4. 


D.  Memory.  (9.5K  +((#  of  coordinates*  127)  DIV  128)  + (2*  # of  blocks)  + (5*  # of 
symbols))  words 


E.  CPU  time. 

1.  Initialization.  Typically  4 seconds  for  a 30  page  program. 

2.  Debugging  requests.  0,07  seconds  per  simple  request.  DDT  response  time. 
Disk  space 


A.  The  .SMI  file  for  a / 7B  compilation  is  typically  one-fourth  the  size  of  the 
corresponding  .REL  file, 


B.  The  ,BAI  file  for  a group  of  /7B  compilations  is  typically  one-third  the  total  size 
of  the  corresponding  .REL  files. 
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SECTION  6 


CURRENT  STATUS 


The  state  of  the  world  is  determined  by  the  values  of  the  accumulators  and  the  value  of 
the  SAIL  variable  '.SKIP!. 


The  run-time  interpreter  recognizes  only  the  first  15  characters  of  identifier  names;  the 
rest  are  discarded  without  comment,  The  characters  which  are  legal  in  identifiers  are 


ABCDEFGHl  JKLMN0PQRSTUV14XYZ 
abcdefghi  jk  I mnopqr stuvuxyz 
01 23456789  !_a0nXc:>V3-*~#8\| 


Notable  for  its  absence:  period. 


LOCATION  of  a procedure  does  not  work. 


PROPS  is  read-only. 


Bracketed  triple  items  are  not  allowed. 


A procedure  call  containing  the  name  of  a parametric  procedure  (functional  argument)  is 
not  handled  properly. 


Contexts  are  not  recognized. 


The  run-time  interpreter  will  not  recognize  macros. 


External  linkage:  If  an  identifier  is  never  referenced  by  code  (i.e.,  has  an  empty  fixup 
chain  at  the  time  fixups  are  put  out  to  the  loader)  then  that  identifier  is  nut  defined  by 
SAIL.  Thus  variables  which  are  never  used  do  not  take  up  space,  and  a request  to  the 
loader  is  not  made  for  EXTERNALS  which  are  not  referenced.  This  feature  of  SAIL  is 
cast  in  concrete  and  will  not  be  changed.  As  a result,  the  following  DOES  NOT  WORK 
unless  special  precautions  are  taken: 

BEGIN 

EXTERNAL  PROCEDURE  BAIL; 

EXTERNAL  PROCEDURE  PL0T(REAL  X0,Y0,X1,Y1); 

REQUIRE  "CALCOM"  LIBRARY; 


BAIL  END 


PLOT  will  not  be  defined  by  SAIL,  hence  BAIL  will  not  know  about  it.  However  if  there 


gr- 


f WWW 
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The  (cUowing 


are  ariy  references  to  PLOT  (real  or  "dummy"  calls)  then  BAIL  will  knew, 
trick  can  also  be  used,  assuming  that  CALCOM  is  a SAIL-compiled  procedure:  Compile 
CALCOM  with  / 1 OB,  which  says  "make  the  .SMI  file  but  don’t  automatically  load 
SYS:BAIL.REL".  Then  the  above  will  win  (due  to  BAIL  recognizing  things  which  are 
globally  unique)  and  programs  which  do  not  use  BAIL  wiL  'ol  have  it  loaded  just  beacuse 
the  library  was  used.  This  same  problem  occurs  ,*;<h  EXTERNAL  RECORD1CLASS 
declarations.  Use  of  the  subfield  index  information  does  not  cause  a reference  to  the 
Mass  raroe  but  NEW'WECO.-aJ  do**  Thu?  the  igrre  /103  (rtck  must  be  used  H there  are 
no  NEWIRECORD  calls. 
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BAIL  is  a debugging  aid  for  SAIL  programs,  where  SAIL  is  an  extended  dialect  of  ALGOLbO 
which  runs. on  the  PDP-10  computer,  BAIL  consists  of  a breakpoint  package  and  an 
expression  interpreter  which  allow  the  user  to  stop  his  program  at  selected  points, 
examine  and  change  the  values  of  variables,  and  evaluate  general  SAIL  expressions,. 

In  addition,  BAIL  can  display  text  from  the  source  file  corresponding  to  the  current 
location  in  the  program.  In  many  respects  BAIL  is  like  DDT  or  RAID,  except  that  BAIL 
is  oriented  towards  SAIL  and  knows  about  SAIL  data  types,  primitive  operations,  and 
procedure  implementation. 
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